.\" $Id: PAPI_set_domain.3,v 1.11.12.1 2006/06/02 19:35:49 maynardj Exp $
.TH PAPI_set_domain 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_set_domain \- set the default execution domain for new event sets

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int PAPI_set_domain(int " domain ");"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_set_domain(C_INT\  domain,\  C_INT\  check )
.BI PAPIF_set_event_domain(C_INT\  EventSet,\  C_INT\  domain,\  C_INT\  check )
.fi

.SH DESCRIPTION
.B "PAPI_set_domain" 
sets the default execution domain for all new event sets created by
.BR "PAPI_create_eventset" (3) 
in all threads. Event sets that are already in existance are not affected. 
To change the domain of an existing event set, please see the 
.BR "PAPI_set_opt" (3)
man page. The reader should note that the domain of an event set
affects only which mode the counter continue to run. Counts are still
aggregated for the current process, and not for any other processes in
the system. Thus when requesting
.BR PAPI_DOM_KERNEL , 
the user is asking for events that occur on behalf of the process,
inside the kernel.

.SH ARGUMENTS
.I "domain"
-- one of the following constants as defined in the papi.h header file:

.TS
allbox tab($);
lB l.
PAPI_DOM_USER$User context counted
PAPI_DOM_KERNEL$Kernel/OS context counted
PAPI_DOM_OTHER$Exception/transient mode counted
PAPI_DOM_SUPERVISOR$Supervisor/hypervisor context counted
PAPI_DOM_ALL$All above contexts counted
PAPI_DOM_MIN$The smallest available context
PAPI_DOM_MAX$The largest available context
.TE

.SH RETURN VALUES
On success, this function returns
.B "PAPI_OK."
 On error, a non-zero error code is returned.

.SH ERRORS
.TP
.B "PAPI_EINVAL"
One or more of the arguments is invalid.
.TP
.B "PAPI_ENOEVST"
The event set specified does not exist.
.TP
.B "PAPI_EISRUN"
The event set is currently counting events.

.SH EXAMPLES
.nf
.if t .ft CW
int retval;

/* Initialize the library */

retval = PAPI_library_init(PAPI_VER_CURRENT);

if (retval > 0 && retval != PAPI_VER_CURRENT) {
  fprintf(stderr,"PAPI library version mismatch!\n");
  exit(1); }

if (retval < 0) 
  handle_error(retval);

if ((retval = PAPI_set_domain(PAPI_DOM_KERNEL)) != PAPI_OK)
  handle_error(retval);

if ((retval = PAPI_create_eventset(&EventSet)) != PAPI_OK)
  handle_error(retval);
.if t .ft P
.fi

.SH BUGS
This function has no known bugs.

.SH SEE ALSO
.BR PAPI_set_opt "(3)" 
